Push Notification

Introduction

---

Push notifications are a powerful tool for engaging users, driving retention, and delivering timely information directly to users’ devices. With Plankton’s integration of Firebase Cloud Messaging (FCM), you can easily implement push notifications in your Unity game for both Android and iOS platforms.

This guide will walk you through the steps needed to set up push notifications using Firebase and Plankton. By the end of this guide, you’ll be able to send and receive notifications, target specific user groups, and enhance your app’s engagement through timely alerts and updates.

Before you begin

---

Prerequisites

• Complete the Plankton setup
• For Android
  • Set Minimum Api Level to 21 or higher
• For iOS
  • Set Target Minimum iOS Version to 15.0 or higher

note

You can change Minimum and Target versions in Unity from Edit > Project Settings > Player > Other Settings

Set up your Firebase project

Android

1. Register your game with Firebase
2. That was all!

iOS

1. Register your game with Firebase
2. Create an APNs authentication key and obtain the Key ID(A 10-character string) and the signing key(a text file with .p8 extension). You request this key from your developer account on developer.apple.com
3. Upload your APNs authentication key in your Firebase project

Confiure Plankton settings

---

1. Open plankton settings by going to Edit > Project Settings > Plankton.
2. Select the checkbox near to Firebase, then select Push Notification.
3. Click Open Firebase Json and open your Firebase configuration file.(It is google-services.json in Android and GoogleService-Info.plist in iOS.)

Implementation

---

Let's dive into codes. Always import the Plankton package in your scripts.

using Plankton;

Access the Registration Token

The registration token is a unique identifier that Firebase Cloud Messaging (FCM) uses to target a specific device for delivering push notifications. Each app instance has its own token, which is required to send notifications to that specific device. To ensure that your game can receive notifications, you need to retrieve and store this token.

To retrieve the token in your game, you can use the PushNotification.GetToken method. This method takes a callback parameter of type System.Action<string>, which returns the token as a string.

Here's how to retrieve the token:

PushNotification.GetToken(token => 
{
    Debug.Log($"FCM Token: {token}");
    // Store the token on your server or locally for future use
});

It's recommended to call this method during your game's startup, so you can store the token in a secure place, such as a remote server, for use in sending notifications.

Keep in mind that the registration token may change under the following circumstances:

• The app is restored on a new device.
• The user uninstalls and reinstalls the app.
• The user clears the app's data.

Make sure to handle these cases by updating the stored token whenever necessary to ensure push notifications are delivered correctly.

Receive Messages

Firebase Cloud Messaging (FCM) allows your game to receive notifications and data messages. When a message is sent to the app, it contains key fields like the notification's title and body, along with any custom data defined during message creation. This enables your game to react to incoming notifications and update the user accordingly.

To handle these messages, you can set a callback using the PushNotification.SetMessageReceivedCallback method. This method accepts a callback of type System.Action<Message>, which will handle incoming notifications. The Message object contains two string fields: title and body, providing the content of the notification.

Here's an example:

PushNotification.SetMessageReceivedCallback(message =>
{
    Debug.Log($"Received Message: Title - {message.title}, Body - {message.body}");
    
    // Handle the message in your game, for example, show a custom notification popup
});

However, note that notification messages received when the app is in the background will not trigger this callback. In such cases, the system automatically handles these notifications, and they are displayed in the device's notification tray. The callback will only be invoked when the app is in the foreground, allowing you to handle the messages manually within the game.

Send messages

You can send messages via the Firebase Admin SDK or the FCM server protocol. You can use the Notifications composer for testing and to send marketing or engagement messages using powerful built-in targeting and analytics.

Send a test notification

Follow these steps to send a test notification and make sure it works:

1. Install and run the app on the target device. You'll need to accept the request for permission to receive notifications.

2. Make sure the app is in the background on the device.

3. In the Firebase console, open the Messaging page.

4. If this is your first message, select Create your first campaign. Then select Firebase Notification messages and select Create.

5. Otherwise, on the Campaigns tab, select New campaign and then Notifications.

6. Enter the message text. All other fields are optional.

7. Select Send test message from the right pane.

8. In the field labeled Add an FCM registration token, enter the registration token you obtained by calling GetToken method.

9. Select Test.

info

To gain a better understanding about the architecture of FCM and its components, read this FCM Architectural Overview.

API Refrences

---

Defined Types

In this section, we will discuss the enumerated types, variables, and classes associated with this feature:

Classes

PushNotification.Message

Field Name	Field Type	Default Value	Field Description
title	string	string.Empty	Title of the notification
body	string	string.Empty	Body of the notification

Method Summaries

Method	Arguments	Return Type	Description
GetToken	System.Action<string> callback	void	Retrieves the device's push notification registration token, which is required for sending notifications to the device. This method takes a callback to handle the token once it's retrieved from Firebase, and it's recommended to call this on game startup to store the token for later use.
SetMessageReceivedCallback	System.Action<Message> callback	void	Sets a callback to handle incoming push notifications when the app is in the foreground. The callback is triggered with the message's content, allowing custom handling of notifications within the game.